docs: add the module and versioning design - #147

Adds docs/Pluto Module Design.md, a design record for modules, dependencies and versioning. Nothing in it is implemented yet: today a directory is the unit of compilation, pt.mod names the module path, and a module cannot use another.

What it records

• No visibility, as decided earlier: everything a module defines is part of its contract, since functions share no mutable state.
• Dependencies in pt.mod, with no import statements: each dependency with the minimum release it needs and an optional alias, usable from every .pt and .spt file. pt.mod also names the oldest compiler the module builds with.
• The standard library ships with the compiler, as a set of libraries. int, float, str, array, complex and math are aliased as . by default and can be re-aliased in pt.mod, so code writes Int(23.2), and there is no implicit std namespace. A function that serves several types lives in one library, such as math's Abs, for the argument types it supports: Min and Max take ordered numbers only.
• No shadowing: functions (by name and input count), constants and struct types each keep a namespace, as in the compiler today, and a name defined twice in one, across a module's own definitions, the standard libraries aliased as . and dependencies aliased as ., is an error. Prefixes are a namespace too. A module sees standard libraries, functions, constants and struct types as of its minimum compiler, so a later library takes no default alias either, and only an unpublished program root may alias a dependency as ..
• Versions in symbols: a dependency's symbols carry its module path and the selected release, which the C ABI already mangles. Majors coexist in one program and their struct types stay distinct, though a generic template accepts either. Struct types in symbols carry only their name today (Struct.Mangle), so that distinction is still to be built.
• Minimal version selection, as in Go, with no lock file. Published releases never change, so the same root pt.mod selects the same releases; the binary also depends on the source, compiler, platform and build settings. Compiled code is cached by everything it was compiled from, every release it depends on transitively included.
• pt.sum and release records: pt.sum verifies dependency manifests and sources and never selects a version, and a mismatch fails the build. A release's record is its checksum-log entry with the proxy's copy; a Git tag alone cannot vouch for contents. A private module's first checksum is checked against a log its owner runs, or taken from the first authenticated download.
• Go-style hosting: releases are tags in each module's own repository, with an optional proxy that keeps copies and an optional public checksum log. Before recording a release, the log reruns the API comparison against the highest release below it in its major line, from its own copy, and refuses too low a version number; it runs no tests and checks no coverage. Private modules skip both services.
• C callers: wrapper symbols keep the major and drop the minor and patch, and structs reach C only as opaque handles, so a struct can still gain a field in a Minor release.
• Programs without a module compile standalone with the compiler's standard library; any other module needs a pt.mod.
• SemVer versions picked when publishing, from a table of minimum categories: publishing numbers each release itself, and the publisher may only ask for a higher category. A function is identified by its name and input count; constants promise their exact values; a struct may gain a field in a Minor release, since literals name their fields and omitted ones take their zero value, and a struct constant keeps its value while its existing fields keep their types and values. Reordering fields is Major.
• The contract is what declarations state, not the argument types tests happen to use, so tests stay representative examples. Rerun tests catch what their assertions or type-sensitive operations expose, and the publisher declares the rest; a narrowing that escapes is a breaking change the release should have declared.
• Publishing steps: build the API manifest, compare it with the release being updated, work out the category from the detected changes and the publisher's declared additions and breaks, run the module's tests, which must pass, and the previous release's tests, whose failures must each be explained by a detected change, a declared break or bug fix, or something outside the contract, require every function body to run at least once, number the release, refusing a lower category than the changes require, and tag it, having the checksum log record a public module's release.
• No deprecation marks: a Major release may remove or change anything, majors coexist so each dependent moves when ready, and release notes list the detected removals and changes plus the publisher's declared breaks and migration steps.
• Development stays permissive: an optional reachability report, execution coverage from tests, and CI decides how strict to be.
• Open questions: how pt.mod spells dependencies, aliases and the minimum compiler, and how code names a dependency's function; who runs the proxy and the checksum log, and how a private module opts out; whether raising the minimum compiler is Minor or Major; what a conversion does with text it cannot read or a value it cannot hold; what module path a standalone program uses; how a publisher declares an addition, break or bug fix and asks for a higher category; backports; whether the major goes in the path or only in the version; what 0.y.z releases promise; which functions get a stable C wrapper; and an inferred check of what each input must support.

Commits

1. docs: the design record.
2. docs: from review: a failing test from the previous release must be explained rather than always stopping publishing; struct constants and Minor field additions; field order; generic calls across majors; what rerun tests catch; the visibility rationale.
3. docs: drops deprecation marks, so compiling never warns about future removals.
4. docs: from review: release notes include declared breaks and migration steps, and the manifest keeps struct field order.
5. docs: publishing picks the version number, so a publisher never chooses one and can only ask for a higher category.
6. docs: from review: publishers declare compatible additions the comparison cannot see (Minor) as well as breaks (Major); release notes are generated; running every function shows it runs, not that it is needed; backports join the open questions.
7. docs: settles the open questions on dependencies and releases: pt.mod without imports, the standard library and its . aliases, no shadowing, minimal version selection with a transitive cache key, versions in symbols, pt.sum, release records and hosting, C callers and standalone programs.
8. docs: from review: collision rules for each kind of name and for prefixes; minimum-compiler visibility for libraries, constants and struct types; no implicit std namespace; Min and Max for ordered numbers; private first use; what the checksum log checks and against which release; conversions join the open questions.

Verification

• Docs only: no commit on this branch changes code. gofmt, go vet and go test -race ./lexer ./parser ./compiler pass, and python3 test.py --leak-check passes 84/84 with every leak check clean, at d7f23f5; the seventh and eighth commits change only the doc.
• The facts the doc relies on were checked: struct literals may omit fields (tests/struct prints Ada 28 0), a template is keyed by name and input count, versioned module paths are valid and mangled (C ABI spec §1.1 and §4.3), and [Double(0:0)] never runs Double's body.
• For the seventh commit: two definitions of one name and input count are already an error (Function Twice with 1 parameters has been previously defined at /a.pt:1:7); Struct.Mangle (compiler/types.go:485) mangles a struct by its name alone; return types are not mangled (C ABI spec §3.4); native and portable PLUTO_TARGET_CPU builds are cached apart; and with no pt.mod above it, the compiler stops with pt.mod not found ... upward.
• For the eighth commit: a constant Pi and a function Pi(x) compile together in one module, as do a constant or a function named after a struct type, so functions, constants and struct types are separate namespaces today.
• Merges cleanly with master after feat(compiler)!: require definite function outputs and stop functions returning ranges #145: this branch only adds a new file, and git merge-tree of the two is clean.

🤖 Generated with Claude Code